feat(examples): generate the catalogue one way, from an empty tree - #484
Merged
Conversation
The runner only wrote. Rename an example's output or delete the example and its old document stayed in target/, published to the site and counted by the guards that read the tree, indistinguishable from a current one. Generation now clears the tree first, and it does so inside the runner — the release script and CI invoke that directly, so a clean step living anywhere else would have covered only the path that already remembered. The test helper stops keeping its own copy of the logic. ShowcaseSync removes the directories it replaces, not only the files, so a category that stops producing anything leaves nothing behind. Two examples were never wired in. One of them, the cover letter, backed a gallery link with a file no code produced; the other renders a preset through a hand-built theme. Both generate now and both have a showcase entry — the cover letter's registered directly, because the helper that builds letter entries points into the layered preset package and this one composes without a preset. Nine committed previews go. Seven were pre-2.0 renders of CV presets the runner already produces under their current names, so every gallery row linked the older snapshot of a preset that had a newer one beside it; those rows now follow the current render. The remaining two, an invoice and a proposal, were left behind by a rename with nothing linking them.
…Windows Clearing the tree before generation moved the risk somewhere else. A run that dies partway now leaves exactly what it managed to write, and the sync's only defence was "not empty" — so it would mirror the remains, delete every published document the run never reached, and rewrite the manifest to match. The site would come out internally consistent and quietly missing half its examples. It refuses now, against the register: that is the one list saying what the catalogue is meant to contain, and deleting an example still shrinks it legitimately because the entry goes with it. Removing the published directories failed on Windows with AccessDeniedException on web/showcase/pdf/templates/schedule — the exact failure the comment I replaced had recorded, and CI could not see it because CI is Linux. Files are still removed strictly; a directory the filesystem will not release is logged and left, because an empty folder nobody can reach through the manifest is not worth failing a publish for. The clean now names the file it could not delete and says a viewer is usually holding it, instead of surfacing a bare AccessDeniedException from a run that has produced nothing yet. The custom Mint Editorial card said the example builds a BrandTheme. It sets one Options field; BrandTheme is a different overload on the same preset, so the description pointed at the wrong one of two adjacent APIs. Two gallery rows linked a preview produced by one example and credited another as its source.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First of two for #461. This one makes the catalogue a statement about the code; the next wires it into
cut-release.ps1and adds the CI diff check. Nothing here touches the release script, CI, the root README or CodeQL.Why
The runner only ever wrote. Rename an example's output or delete the example, and its old document stayed in
target/generated-pdfs— copied to the site, counted by the guards that read the tree, and indistinguishable from a document the current code produces. The tree recorded the order in which commands had been run rather than what the code does.Measured on
develop: five example classes were never wired into the runner, and ten committed previews had no generated source. They are the same story from two ends.CvFileExampleandCvModernV2Exampleturn out to render the identical document — same factory, same fixture — which is why one of them was never wired in.CoverLetterFileExamplewas not in the runner.What
One canonical path.
ExampleOutputPaths.clean()empties the tree, andGenerateAllExamplescalls it before writing. The clean step lives in the runner because the release script and CI invoke the runner directly — putting it anywhere else would cover only the path that already remembered.GeneratedCataloguestops keeping its own copy and delegates.ShowcaseSyncmirrors. It already cleared the published files; it now removes the directories too, so a category that stops producing anything leaves nothing behind on the deployed tree.Two examples wired in.
CoverLetterFileExampleandCvMintEditorialCustomExample. Both have showcase entries; the cover letter's is registered directly rather than through theletter()helper, which points into the layered preset package — this example composes without a preset, and the source-link guard caught the mismatch.Nine previews removed, seven replaced. The gallery rows follow the current render. The catalogue and the register now agree exactly: 93 documents, 93 entries, no placeholder cards, no entry without a document.
The two gallery examples stay unwired on purpose: they render one document per preset, 31 in all, duplicating the individual preset examples under their pre-2.0 names. Publishing them is a decision about what the showcase is for, not a gap.
Tests
examplessuite: 52 tests,BUILD SUCCESS.qagate: 688. Core guard job: 37.codeUrlresolves to a file